home *** CD-ROM | disk | FTP | other *** search
/ Macworld Expo - Develope…Central & Net Innovations / Developer Central and Net Innovators (MacWorld Expo) (January 1999).iso / Developer Central / Metrowerks CodeWarrior / CodeWarrior Pro 4 Release Notes / PowerPlant Notes / Network Classes Notes < prev    next >
Encoding:
Text File  |  1998-08-25  |  12.2 KB  |  263 lines  |  [TEXT/CWIE]
  1. ========================================================================
  2. Metrowerks PowerPlant Networking Classes Release Notes 
  3. ========================================================================
  4.  
  5. Version: PowerPlant 1.9.2
  6. Date:     09 August 1998
  7. Author:  Frank Vernon, Eric Scouten
  8. ========================================================================
  9.  
  10.    Request for comment:
  11.  
  12.    Since their release we have had sporadic requests that the
  13.    PowerPlant Networking Classes be expanded to support other IP and, 
  14.    non-IP related protocols. Suggestions have included RawIP, AppleTalk, 
  15.    SOCKET style interfaces, and others. In addition, some have 
  16.    suggested dropping MacTCP support altogether and focusing instead 
  17.    on the advantages of the OpenTransport API.
  18.    
  19.    We are presently considering these as well as other networking
  20.    related issues for future development. If you have any input on what
  21.    you would like to see in terms of general network support for 
  22.    PowerPlant, please contact Metrowerks tech support with your 
  23.    suggestions.
  24.     
  25.  
  26. ========================================================================
  27. New Features in This Version
  28. ========================================================================
  29.  
  30. *  ICMP message handling for the UDP classes has been updated and 
  31.    improved for the CWPro4 release. ICMP messages are now handled
  32.    like all other asynchronous and unexpected network events.
  33.  
  34.  
  35. ========================================================================
  36. Bugs Fixed in This Version
  37. ========================================================================
  38.  
  39. *  Fixed issue introduced with last release that prevented both MacTCP
  40.    and OpenTransport code from being used in the same project.
  41.    
  42. *  Remove #pragma direct_destruction instructions. This no longer
  43.    necessary for (nor supported by) the latest MW compilers. This was
  44.    not a bug and will not effect any code you may have using these
  45.    options. These options are now simply ignored by the compiler and
  46.    thus the code was removed for completeness.
  47.    
  48. *  Fix to StOpenTptOperation::WaitForCompletion to prevent memory leak
  49.    in the case of an exception within the routine.
  50.  
  51.  
  52. ========================================================================
  53. Known Bugs and Incompatibilities
  54. ========================================================================
  55.  
  56. *  NONE
  57.  
  58.  
  59. ========================================================================
  60. Additional Notes
  61. ========================================================================
  62.  
  63. These new classes represent a radical shift from the pre-CW11 Networking
  64. Classes. Updates, possibly even entire code redesigns, will be necessary
  65. to any existing code bases using the old classes.
  66.  
  67. To familiarize yourself with the new classes, it is suggested you read
  68. these release notes, review the architectural outline below, and closely
  69. study the included example code.
  70.  
  71. The two included examples are SimpleServer and SimpleClient.
  72. SimpleClient is equivalent to the old PowerTelnet example. SimpleServer
  73. is essentially the same as the version included with the old Net
  74. Classes. You can use these two examples together (the client connecting
  75. to the server) to experiment with the various features of the new
  76. classes. Both of these examples have been updated to demonstrate basic
  77. UDP usage as well as TCP.
  78.  
  79.     NOTE:  If you are testing the Client/Server combination with the
  80.            client and server running on the same machine, you may have
  81.            unpredictable results. It is recommended that you run these
  82.            applications on separate machines.
  83.  
  84. This is a brief outline of the major classes and concepts found in the
  85. new PowerPlant Networking Classes. Not all of the classes are described
  86. here. A brief description of each class is typically available at the
  87. top of each source file.
  88.  
  89. The prefix 'Int_' in method names indicates methods which might be
  90. called at interrupt time. This is a convention that we hope will help
  91. you know where you should be careful setting break points in the debugger.
  92. All exposure in the public interfaces to interrupt time has been removed 
  93. in the new classes. Where interrupt code couldn't be avoided however (for
  94. completion routines for instance) this convention has been used. If you
  95. find yourself in one of these routines while in the debbuger you should
  96. anticipate unusual and unreliable results.
  97.  
  98. ===================== Changes from Pre-CW11 Classes ====================
  99.  
  100. The most notable change in the new classes is the elimination of the
  101. "EventLoop" style notifier and, in fact, the entire notifier concept.
  102. Where notification of unexpected events is required, the standard
  103. PowerPlant Broadcast and Listen mechanism has been used. The new classes
  104. are entirely threaded and require the use of the PowerPlant Thread
  105. classes. These decisions have allowed us to greatly reduce both the
  106. amount and the complexity of the code that must be executed at interrupt
  107. time. In the new Networking Classes, your exposure to dealing with events 
  108. at interrupt time is essentially eliminated.
  109.  
  110. Another important omission from the new Net Classes is the concept of
  111. the Memory Pool. Since exposure to events at interrupt time is removed,
  112. much of the necessity for the Memory Pool has also been eliminated. The
  113. Memory Pool is still being used internally to handle messages generated
  114. at interrupt time, but its use is completely transparent to your
  115. applications. A single static pool is automatically created when
  116. necessary and deletes itself when no longer required. It is no longer
  117. necessary that you concern yourself with ensuring that your data will
  118. fit within an arbitrarily sized memory pool. You are free to allocate
  119. and deallocate memory using normal memory management techniques.
  120.  
  121. The disconnect sequence on both MacTCP and OT is a little different from
  122. the old Networking Classes. We now have two calls: Disconnect and
  123. SendDisconnect which do different things. SendDisconnect will send a
  124. "orderly disconnect" and return immediately so you can continue to
  125. receive data. (We also have a RecieveDisconnect method to handle the
  126. other side of this equation.) Disconnect on the other hand will send an
  127. orderly disconnect and block the thread until the remote side has shut
  128. down. In addition, Disconnect is smart enough to call ReceiveDisconnect
  129. when necessary. In most instances, you will only need to call Disconnect
  130. when you are ready to close a connection. SendDisconnect, however,
  131. should allow people with more sophisticated send/receive requirements to
  132. handle one-sided connection closures properly.
  133.  
  134. The "OT on 68k" defaults have been changed. We now check for OT version
  135. 1.1 and allow OT calls from 68k code. There is still a compile option
  136. for disabling this, but the default is now to use OT whenever possible.
  137.  
  138. It is now possible to Abort almost any pending network operation under
  139. both MacTCP and OpenTransport. The method AbortThreadOperation() will
  140. abort the pending operation on the thread specified, resume the thread,
  141. and throw a Networking Classes specific error (Abort_Error.) Please note
  142. that neither MacTCP or OpenTransport really support the concept of
  143. aborting a pending network operation. This feature simply resumes your
  144. thread and knows how to handle the dangling event when the completion
  145. routine fires. Due to this, there are some instances where you may have
  146. to wait until the routine actually completes before you will be allowed
  147. to quit the application. The Networking classes handle these situations
  148. transparenlty however and no additional coding is required on your part
  149. to ensure compatibility.
  150.  
  151. Timeouts (where applicable) are now implemented for both MacTCP and
  152. OpenTransport. As with the Abort feature above, since OpenTransport does
  153. not typically support the timeout concept, this feature simply resumes
  154. your thread and knows how to handle the dangling event when the
  155. completion routine fires. For consistency with both OpenTransport and
  156. MacTCP, timeout condition errors will all throw a Networking Classes
  157. specific error (Timeout_Error.)
  158.  
  159. =========================== Public Interfaces ==========================
  160.  
  161. LEndpoint- Encapsulates the idea of a "network endpoint," or one side of
  162. a two-way communication link. The endpoint is the object that is used to
  163. send or receive data over the network.
  164.  
  165. LTCPEndpoint-
  166. LUDPEndpoint- These classes inherit from LEndpoint and represent TCP/IP
  167. and UDP style connections. An appropriate instance of one of these
  168. classes would be created as a representation of the local side the
  169. network connection.
  170.  
  171. LInternetAddress- This class represents both IP and DNS style addresses.
  172. It will automatically map between DNS style and IP style addresses for
  173. you as necessary.
  174.  
  175. UNetworkFactory- You will use this class to create network endpoints. It
  176. will choose the best configuration (i.e. MacTCP or OpenTransport) given
  177. the system software that is installed on the host machine.
  178.  
  179. ==================== Internal Implementation Details ===================
  180.  
  181. LInternetMapper- Encapsulates the idea of the domain name server for
  182. Internet hosts. The mapper is the object that is used to find the
  183. address of another computer on the network. This is used primarily by
  184. LNetworkAddress to convert addresses for you behind the scenes. Most if
  185. not all DNS operations will be transparent, under normal circumstances,
  186. through the use of a LInternetAddress object.
  187.  
  188. UMacTCPSupport-
  189. UOpenTptSupport- Utility classes for handling MacTCP and OpenTransport
  190. specific functions.
  191.  
  192. LMacTCPEndpoint-
  193. LOpenTptEndpoint- A representation of a LTCPEndpoint that uses either
  194. MacTCP or OpenTransport. One of these will typically be created for you
  195. when you use UNetworkFactory to create an endpoint.
  196.  
  197. LMacTCPInetMapper-
  198. LOpenTptInetMapper- A representation of a LInternetMapper that uses
  199. either MacTCP or OpenTrasport. Again use of these classes is transparent
  200. through the use of LInternetAddress.
  201.  
  202. StAsyncOperation- Encapsulates the idea of a single network operation
  203. and is primarily responsible for blocking/resuming the communication
  204. thread as necessary. This is used internally by the Net Classes and you
  205. would not normally ever work directly with an object of this type.
  206. Almost all activities that might need to happen at interrupt time are
  207. handled within classes of this type.
  208.  
  209. StMacTCPTCPOperation-
  210. LMacTCPDNSOperation-
  211. StMacTCPUDPOperation-
  212. StOpenTptOperation- Representations of StAsyncOperation for MacTCP and
  213. OpenTransport. Since MacTCP and OpenTransport work in fundamentally
  214. different fashions, the actual operation of these classes is
  215. significantly different. The use of these classes is transparent under
  216. normal circumstances. Note that for technical reasons associated with
  217. aborting DNS operations, the class LMacTCPDNSOperation is NOT stack safe
  218. unlike the other classes in this category.
  219.  
  220. A new feature allows local caching of canonical names and IP
  221. addresses that will be searched before a DNS server is queried.
  222. This gives you the ability to specify specific name and address
  223. mappings if necessary and may improve performance in some
  224. instances.
  225.  
  226. Usage:
  227. This feature is normally disabled. Two #defines in
  228. LInternetMapper.h control its operation.
  229.     DNS_USECACHE - If set to a non-zero value will cause all
  230.         DNS lookups to check the local cache before attempting
  231.         to query a DNS server for address resolution.
  232.  
  233.     DNS_CACHELOOKUPS - If set to a non-zero value will cause all
  234.         DNS lookups returned from a DNS server to be added to
  235.         the local cache. 
  236.  
  237.         NOTE:    Please be careful using the DNS_CACHELOOKUPS
  238.                 feature as it will circumvent dynamic name
  239.                 servers and thus may reduce performance on
  240.                 those sites.
  241.  
  242. To add mappings to the cache use UDNSCache::AddToDNSCache(). This
  243. function allows you to maintain and dynamically load you own local
  244. hosts tables.
  245.  
  246.  
  247. ========================================================================
  248. Contacting Metrowerks
  249. ========================================================================
  250.  
  251. For bug reports, technical questions, and suggestions, please use the
  252. forms in the Release Notes folder on the CD, and send them to
  253.  
  254. support@metrowerks.com
  255.  
  256. See the CodeWarrior on the Nets document in the Release Notes folder for
  257. more contact information, including a list of Internet newsgroups, 
  258. online services, and patch and update sites.
  259.  
  260. ========================================================================
  261.  
  262. Metrowerks Corporation
  263.